Skip to main content

生成API文档

【关于API Blueprint】

dingo api允许我们使用命令:

php artisan api:doc --output-file "D:\api.apib"

生成API Blueprint 1A 格式的文档;前提是我们已经为我们的控制器和方法写好了注释,比如:

<?php
namespace App\Http\Controllers\Api\V1;

use Illuminate\Http\Request;
use App\Http\Requests;
use App\Http\Controllers\Controller;

/**
 * 用户资源    
 * 
 * <br/>[注意]:每个部门下的节点不能超过3万个。
 * 
 * @Resource("Group User")
 */
class UserController extends ApiBaseController
{
    /**
     * 根据用户ID获取用户
     * 
     * [需授权] 返回单个用户
     * 
     * @Get("/api/user/ID")
     * @Parameters({
     *      @Parameter("id", type="integer", required=true, description="用户ID")
     * })
     * @Request(headers={"Authorization": "Bearer token"})
     * @Response(200, body={})
     */
    public function show($id)
    {
       //
    }

}

像上面这样写好注释后,使用 api:doc 命令行就会生成标准的 api blueprint 文档了。

【关于aglio】

那么,我们现在有了markdown写法的api blueprint文档了,怎么把它转换成可读的html文档呢?aglio神器就来了。aglio的github地址:https://github.com/danielgtaylor/aglio 注意安装aglio需要先安装NODE.JS,然后利用NPM安装即可:

npm install -g aglio

至于怎么安装node.JS 不是本文的关注点,各位自行搜索。

好了,安装aglio完毕我们就可以使用命令行生成可读的html格式的api文档了:

aglio -"D:\api.apib" -"D:\api.html"

生成的api文档如下:

到此,一套比较完善的api文档就新鲜出炉啦。

为了避免每次都要打2次命令,我们可以写一个命令脚本 ApiCreate.bat,比如:

@echo off
echo "API Create Command Tool"
echo Current directory is: %cd%
cd %cd%
::先生成api blueprint格式文档
call php artisan api:doc --output-file %cd%"\api.apib"
::用aglio工具转化成html文档 --theme-full-width
call aglio -%cd%"\api.apib" -%cd%"\public\api.html"
pause

这样以后要生产api文档,只要点击执行该bat脚本就可以啦。

关于生成api文档还有另外一个不错的工具:Swagger http://swagger.io/ 飘易会在另外的文章里单独说一说。